﻿////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// <copyright>Copyright 2008-2011 Andreas Huber Doenni</copyright>
// Distributed under the Microsoft Public License (Ms-PL).
// See accompanying file License.txt or copy at http://mews.codeplex.com/license.
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

namespace Mews.Net.Nntp.Cache
{
    using System;
    using System.Collections;
    using System.Collections.Generic;
    using System.Diagnostics.CodeAnalysis;

    /// <summary>Represents an NNTP group, the articles of which are cached locally.</summary>
    /// <threadsafety static="true" instance="false"/>
    public interface IGroup : IDeletablePersistentObject, IEquatable<IGroup>
    {
        /// <summary>Gets the host on which this group is hosted.</summary>
        IHost Host
        {
            get;
        }

        /// <summary>Gets the NNTP name of the group.</summary>
        string Name
        {
            get;
        }

        /// <summary>Gets or sets the display name of the group.</summary>
        /// <exception cref="ArgumentException">Attempted to set a value the length of which exceeds the maximum allowed
        /// length.</exception>
        /// <exception cref="ArgumentNullException">Attempted to set <c>null</c> as a value.</exception>
        string DisplayName
        {
            get;
            set;
        }

        /// <summary>Gets or sets the maximum number of new articles for which information is received during each
        /// send/receive operation started with <see cref="Cache.StartSendReceive"/>.</summary>
        /// <exception cref="ArgumentOutOfRangeException">Attempted to set a value that is 0, negative or greater than
        /// <see cref="CachedInboundArticlesLimit"/>.</exception>
        /// <remarks>Only articles where <see cref="IInboundArticle.IsBeingWatched"/> is <c>false</c> count toward this
        /// limit. In any event, the full content is received for all articles that have had their
        /// <see cref="IInboundArticle.IsBeingWatched"/> property set to <c>true</c>.</remarks>
        int NewInboundArticlesReceiveLimit
        {
            get;
            set;
        }

        /// <summary>Gets or sets the maximum number of articles that are held in the cache.</summary>
        /// <exception cref="ArgumentOutOfRangeException">Attempted to set a value that is less than
        /// <see cref="NewInboundArticlesReceiveLimit"/>.</exception>
        /// <remarks>This number is enforced in the <see cref="Cache.Compact">Cache.Compact</see> method.</remarks>
        int CachedInboundArticlesLimit
        {
            get;
            set;
        }

        /// <summary>Gets or sets the filter employed by <see cref="QueryCache.GetOriginalInboundArticles()"/> and
        /// <see cref="QueryCache.GetThreadCount()"/>.</summary>
        InboundArticleFilter InboundArticleFilter
        {
            get;
            set;
        }

        /// <summary>Gets an object that offers the means to efficiently execute a query multiple times.</summary>
        /// <remarks>The returned object must be disposed after use.</remarks>
        [SuppressMessage("Microsoft.Design", "CA1024:UsePropertiesWhereAppropriate", Justification = "Every call to this method returns a new object that needs to be disposed.")]
        QueryCache CreateQueryCache();

        /// <summary>Gets all articles that do not reference another article and match the criteria defined by
        /// <paramref name="filter"/>.</summary>
        /// <exception cref="InvalidOperationException"><see cref="Cache.Dispose"/> has been called on the parent
        /// <see cref="Cache"/> object.</exception>
        /// <remarks>The documented exceptions are never thrown from this method but from the
        /// <see cref="IEnumerator.MoveNext"/> method.</remarks>
        [SuppressMessage("Microsoft.Design", "CA1024:UsePropertiesWhereAppropriate", Justification = "This is an expensive operation.")]
        IEnumerable<IInboundArticle> GetOriginalInboundArticles(InboundArticleFilter filter);

        /// <summary>Gets the number of articles that do not reference another article and match the criteria defined by
        /// <paramref name="filter"/>.</summary>
        /// <exception cref="InvalidOperationException"><see cref="Cache.Dispose"/> has been called on the parent
        /// <see cref="Cache"/> object.</exception>
        [SuppressMessage("Microsoft.Design", "CA1024:UsePropertiesWhereAppropriate", Justification = "This is an expensive operation.")]
        int GetThreadCount(InboundArticleFilter filter);

        /// <summary>Sets the <see cref="IInboundArticle.HasBeenRead"/> property of all articles of this group to
        /// <c>true</c>.</summary>
        void MarkAllInboundArticlesAsRead();
    }
}
